home *** CD-ROM | disk | FTP | other *** search
/ Your Choice 1 / your choice.zip / your choice / PRGMMING / CX201 / BINIO.DOC < prev    next >
Text File  |  1994-03-01  |  5KB  |  185 lines
  1.  
  2. BINIO routines
  3. --------------------------------------------------------------------------
  4.    The BINIO routines provide input and output access to files.
  5.    BINIO stands for 'BINary Input and Output'.  Binary meaning any type
  6.    of file.  The BINIO functions will be familiar to many programmers.
  7.  
  8.  
  9. BINIO Programming Interface
  10. --------------------------------------------------------------------------
  11.  
  12.    Constants
  13.    -----------------------------------------------------------------------
  14.    BINIO_OPEN_READ   -  open for read access only
  15.    BINIO_OPEN_WRITE  -  open for read and write access
  16.    BINIO_OPEN_CREATE -  create file and open with read and write access
  17.    BINIO_SEEK_SET    -  seek from beginning of file
  18.    BINIO_SEEK_CUR    -  seek from current file pointer position
  19.    BINIO_SEEK_SET    -  seek from end of file
  20.  
  21.  
  22.    binio_open(name, mode)
  23.    -----------------------------------------------------------------------
  24.    PURPOSE:
  25.       Open a file.
  26.  
  27.    PARAMETERS:
  28.    
  29.       name
  30.             name of file to open
  31.  
  32.       mode
  33.             open mode (one of BINIO_OPEN_*)
  34.  
  35.    RETURN VALUE:
  36.  
  37.       -1
  38.             could not open file
  39.  
  40.       else
  41.             handle to opened file
  42.  
  43.    NOTES:
  44.       The file pointer is set to 0 for all opened files.
  45.    
  46.  
  47.    binio_close(handle)
  48.    -----------------------------------------------------------------------
  49.    PURPOSE:
  50.       Close a file opened with binio_open.
  51.  
  52.    PARAMETERS:
  53.    
  54.       handle
  55.             handle to opened file (from binio_open)
  56.  
  57.  
  58.    RETURN VALUE:
  59.  
  60.       -1
  61.             could not close file
  62.  
  63.        0
  64.             file was successfully closed
  65.  
  66.  
  67.    binio_read(handle, buffer, bytes)
  68.    -----------------------------------------------------------------------
  69.    PURPOSE:
  70.       Read data from a file, at the current file pointer position.
  71.  
  72.    PARAMETERS:
  73.    
  74.       handle
  75.             handle to opened file (from binio_open)
  76.  
  77.       buffer
  78.             memory buffer where data will be placed
  79.  
  80.       bytes
  81.             bytes to read (0-65534)
  82.  
  83.  
  84.    RETURN VALUE (32 bit integer):
  85.  
  86.       -1    An error occurred.
  87.  
  88.       else  Bytes actually read.  This may be less than the bytes requested,
  89.             indicating an error condition, or an attempt to read past the
  90.             end of file.
  91.  
  92.  
  93.    binio_write(handle, buffer, bytes)
  94.    -----------------------------------------------------------------------
  95.    PURPOSE:
  96.       Write data to a file, at the current file pointer position.
  97.  
  98.    PARAMETERS:
  99.    
  100.       handle
  101.             handle to opened file (from binio_open)
  102.  
  103.       buffer
  104.             memory buffer containing data to write
  105.  
  106.       bytes
  107.             bytes to write (0-65534)
  108.  
  109.  
  110.    RETURN VALUE (32 bit integer):
  111.  
  112.       -1    An error occurred.
  113.  
  114.       else  Bytes actually written.  This may be less than the bytes
  115.             requested, indicating an error condition.
  116.  
  117.  
  118.    binio_seek(handle, offset, where)
  119.    -----------------------------------------------------------------------
  120.    PURPOSE:
  121.       Position the file pointer.
  122.  
  123.    PARAMETERS:
  124.    
  125.       handle
  126.             handle to opened file (from binio_open)
  127.  
  128.       offset
  129.             where to position to
  130.  
  131.       where
  132.             may be one of:
  133.                BINIO_SEEK_SET - using offset, seek to physical position
  134.                BINIO_SEEK_CUR - using offset, seek from current position
  135.                BINIO_SEEK_END - using offset, seek from end of file
  136.  
  137.    RETURN VALUE (32 bit integer):
  138.  
  139.       -1    An error occurred.
  140.  
  141.       else  The current file pointer position.
  142.  
  143.    NOTES:
  144.       The file pointer is 0 based.
  145.       Seeking with negative values is allowed.
  146.       binio_seek(handle, 0, BINIO_SEEK_END) seeks to the end of file.
  147.  
  148.  
  149.    binio_tell(handle)
  150.    -----------------------------------------------------------------------
  151.    PURPOSE:
  152.       Retrieve the current file pointer position.
  153.  
  154.    PARAMETERS:
  155.    
  156.       handle
  157.             handle to opened file (from binio_open)
  158.  
  159.    RETURN VALUE (32 bit integer):
  160.  
  161.       -1    An error occurred.
  162.  
  163.       else  The current file pointer position.
  164.  
  165.    NOTES:
  166.       The file pointer is 0 based.
  167.  
  168.  
  169.    binio_length(handle)
  170.    -----------------------------------------------------------------------
  171.    PURPOSE:
  172.       Retrieve the length (in bytes) of an opened file.
  173.  
  174.    PARAMETERS:
  175.    
  176.       handle
  177.             handle to opened file (from binio_open)
  178.  
  179.    RETURN VALUE (32 bit integer):
  180.  
  181.       -1    An error occurred.
  182.  
  183.       else  The current file length.
  184.  
  185.